<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></meta><title>Drakma - A Common Lisp HTTP client</title><meta name="description" content="
    Drakma is a full-featured HTTP client implemented in Common Lisp.
    It knows how to handle HTTP/1.1 chunking,
    persistent connections, re-usable sockets, SSL, continuable uploads, file uploads, cookies, and more.
  "></meta><style type="text/css">
  body { background-color: #ffffff }
  pre { padding:5px; background-color:#e0e0e0 }
  pre.none { padding:5px; background-color:#ffffff }
  h3, h4, h5 { text-decoration: underline; }
  .entry-type { padding-left: 1em; font-size: 60%; font-style: italic }
  a { text-decoration: none; padding: 1px 2px 1px 2px; }
  a:visited { text-decoration: none; padding: 1px 2px 1px 2px; }
  a:hover { text-decoration: none; padding: 1px 1px 1px 1px; border: 1px solid #000000; } 
  a:focus { text-decoration: none; padding: 1px 2px 1px 2px; border: none; }
  a.none { text-decoration: none; padding: 0; }
  a.none:visited { text-decoration: none; padding: 0; } 
  a.none:hover { text-decoration: none; border: none; padding: 0; } 
  a.none:focus { text-decoration: none; border: none; padding: 0; } 
  a.noborder { text-decoration: none; padding: 0; } 
  a.noborder:visited { text-decoration: none; padding: 0; } 
  a.noborder:hover { text-decoration: none; border: none; padding: 0; } 
  a.noborder:focus { text-decoration: none; border: none; padding: 0; }  
        </style></head><body>
  
  

  <h2>Drakma - A Common Lisp HTTP client</h2>

  <blockquote>
    <h3 xmlns=""><a class="none" name="abstract">Abstract</a></h3>
      <p>
        Drakma is a full-featured HTTP client implemented in Common
        Lisp.  It knows how to handle <a href="#chunked">HTTP/1.1
        chunking</a>, <a href="#arg-keep-alive">persistent
        connections</a>, <a href="#ex-reuse-connection">re-usable
        sockets</a>, <a href="#ex-chunked-https">SSL</a>, <a href="#ex-assemble-request-content">continuable uploads</a>,
        <a href="#arg-parameters">file uploads</a>, <a href="#arg-cookie-jar">cookies</a>, and more.
      </p>
      <p>
        The code comes with a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style
        license</a> so you can basically do with it whatever you want.
      </p>
    
  </blockquote>

  <h3 xmlns=""><a class="none" name="contents">Contents</a></h3>
  <ol xmlns="">
<li><a href="#abstract">Abstract</a></li>
<li><a href="#contents">Contents</a></li>
<li>
<a href="#examples">Examples</a><ol>
<li><a href="#ex-loading">Loading Drakma with Quicklisp</a></li>
<li><a href="#ex-logging">Log headers to the REPL output stream</a></li>
<li><a href="#ex-request-redirect">Requesting a page with redirection</a></li>
<li><a href="#ex-charsets">Requesting a page containing non-ASCII characters</a></li>
<li><a href="#ex-binary-data">Requesting binary data</a></li>
<li><a href="#ex-chunked-https">Chunked transfers and HTTPS</a></li>
<li><a href="#ex-fake-ua">Faking a user agent header</a></li>
<li><a href="#ex-post-and-cookie">Posting data and using cookies</a></li>
<li><a href="#ex-reuse-connection">Reusing a connection to a server</a></li>
<li><a href="#ex-basic-auth">Basic Authorization</a></li>
<li><a href="#ex-response-stream">Reading the response from a stream</a></li>
<li><a href="#ex-assemble-request-content">Piecemeal assembly of request contents</a></li>
<li><a href="#ex-partial-transfers">Partial transfers</a></li>
</ol>
</li>
<li><a href="#install">Download and Installation</a></li>
<li><a href="#patches">Development and patches</a></li>
<li>
<a href="#dictionary">The Drakma dictionary</a><ol>
<li><a href="#dict-request">Requests</a></li>
<li><a href="#headers">Headers</a></li>
<li><a href="#cookies">Cookies</a></li>
<li><a href="#conditions">Conditions</a></li>
</ol>
</li>
<li><a href="#index">Symbol index</a></li>
</ol>
    
  <h3 xmlns=""><a class="none" name="examples">Examples</a></h3>

    <style type="text/css">
      body { margin-left: 2em; }
      p, blockquote { max-width: 45em; }
      pre { margin-left: 3em; margin-right: 3em; word-wrap: break-word; overflow-x: auto; background: #eee; }
      .arglist-spacer { margin-left: 6em; max-width: 45em; }
      .repl-output { color: black; }
      .repl-input { font-weight: bold; }
      .headers-out { color: SteelBlue; }
      .headers-in { color: SeaGreen; }
    </style>

    <p>
      Here is a collection of example uses of Drakma to which
      demonstrate some of its features.  In the examples, text is
      color coded to indicate where it comes from (<tt><span class="repl-input">REPL input</span>, <span class="repl-output">REPL output</span>, <span class="headers-out">HTTP headers sent</span></tt> and <tt><span class="headers-in">HTTP headers received</span></tt>).  Headers
      particularly relevant to the example at hand are shown <tt><span class="headers-out"><b>in</b></span> <span class="headers-in"><b>bold</b></span></tt>.
    </p>

    <h4 xmlns=""><a name="ex-loading">Loading Drakma with Quicklisp</a></h4>
      <pre><span class="repl-output">? </span><span class="repl-input">(ql:quickload :drakma)</span>
<span class="repl-output">To load "drakma":
  Load 1 ASDF system:
    drakma
; Loading "drakma"
To load "cl+ssl":
  Load 1 ASDF system:
    flexi-streams
  Install 8 Quicklisp releases:
    alexandria babel bordeaux-threads cffi cl+ssl
    trivial-features trivial-garbage trivial-gray-streams
...
; Loading "drakma"

(:DRAKMA)
</span>
</pre>
    
    <h4 xmlns=""><a name="ex-logging">Log headers to the REPL output stream</a></h4>
      <p>
        In some of the following examples, the headers exchanged
        between Drakma and the HTTP server should be shown, for
        illustration purposes.  This can be achieved like so:
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(setf drakma:*header-stream* *standard-output*)</span>
<span class="repl-output">#&lt;SYNONYM-STREAM to *TERMINAL-IO* #x3020006AC7DD&gt;</span>
</pre>
    
    <h4 xmlns=""><a name="ex-request-redirect">Requesting a page with redirection</a></h4>
      <p>
        Request a page.  Note how Drakma automatically follows the 301
        redirect and how the fourth return value shows the
        <em>new</em> URI.
      </p>
<pre><span class="repl-output">? </span><span class="repl-input">(<a href="#http-request">drakma:http-request</a> "http://lisp.org/")</span>
<span class="headers-out">GET / HTTP/1.1
Host: lisp.org
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 <b>307  Temporary Redirect</b>
Date: Sun, 09 Dec 2012 08:01:56 GMT
Connection: Close
Server: AllegroServe/1.2.65
Transfer-Encoding: chunked
<b>LOCATION: http://lisp.org/index.html</b>
</span>
<span class="headers-out"><b>GET /index.html HTTP/1.1</b>
Host: lisp.org
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200  OK
Date: Sun, 09 Dec 2012 08:01:56 GMT
Connection: Close
Server: AllegroServe/1.2.65
Content-Type: text/html
Content-Length: 459
LAST-MODIFIED: Wed, 26 Oct 2011 02:26:26 GMT
</span>
<span class="repl-output">"&lt;HTML&gt;
&lt;HEAD&gt;
  &lt;title&gt;John McCarthy, 1927-2011&lt;/title&gt;
  &lt;STYLE type=\"text/css\"&gt;
    BODY {text-align: center}
  &lt;/STYLE&gt;
&lt;/HEAD&gt;
&lt;BODY&gt;
&lt;h1&gt;John McCarthy&lt;/h1&gt;
&lt;img src=\"jmccolor.jpg\" alt=\"a picture of John McCarthy, from his website\"/&gt;
&lt;h3&gt;1927-2011&lt;/h3&gt;
&lt;br&gt;&lt;br&gt;
&lt;a href=\"http://www-formal.stanford.edu/jmc/\"&gt;John McCarthy's Home Page&lt;/a&gt;&lt;br&gt;
&lt;a href=\"http://news.stanford.edu/news/2011/october/john-mccarthy-obit-102511.html\"&gt;Obituary&lt;/a&gt;
&lt;/BODY&gt;
&lt;/HTML&gt;
"
200
((:DATE . "Sun, 09 Dec 2012 08:01:56 GMT") (:CONNECTION . "Close") (:SERVER . "AllegroServe/1.2.65")
 (:CONTENT-TYPE . "text/html") (:CONTENT-LENGTH . "459") (:LAST-MODIFIED . "Wed, 26 Oct 2011 02:26:26 GMT"))
#&lt;URI http://lisp.org/index.html&gt;
#&lt;FLEXI-STREAMS:FLEXI-IO-STREAM #x30200155DB1D&gt;
T
" OK"</span>
</pre>
    
    <h4 xmlns=""><a name="ex-charsets">Requesting a page containing non-ASCII characters</a></h4>
      <p>
        Drakma automatically interprets the 'charset=utf-8' part
        correctly.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(subseq (<a href="#http-request">drakma:http-request</a> "http://www.cl.cam.ac.uk/~mgk25/ucs/examples/digraphs.txt") 0 298)</span>
<span class="headers-out">GET /~mgk25/ucs/examples/digraphs.txt HTTP/1.1
Host: www.cl.cam.ac.uk
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:15:04 GMT
Server: Apache/2.2.3 (CentOS)
Last-Modified: Mon, 06 Apr 2009 18:13:43 GMT
ETag: "17cd62-298-466e6dbcd03c0"
Accept-Ranges: bytes
Content-Length: 664
X-UA-Compatible: IE=edge
Connection: close
<b>Content-Type: text/plain; charset=utf-8</b>
</span>
<span class="repl-output">"Latin Digraphs and Ligatures in ISO10646-1

A short table of ligatures and digraphs follows. Some of these may not be
ligatures/digraphs in the technical sense, (for example, æ is a seperate
letter in English), but visually they behave that way.

AÆE : U+00C6
aæe : U+00E6
ſßs : U+00DF
IĲJ : U+0132"</span>
</pre>
    
    <h4 xmlns=""><a name="ex-binary-data">Requesting binary data</a></h4>
      <p>
        For non-textual content types, a vector of octets is returned.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(<a href="#http-request">drakma:http-request</a> "https://api.github.com/repos/edicl/drakma/git/tags/tag-does-not-exist")</span>
<span class="headers-out">GET /repos/edicl/drakma/git/tags/tag-does-not-exist HTTP/1.1
Host: api.github.com
User-Agent: Drakma/1.3.0 (SBCL 1.1.1.31.master.2-9fac43f-dirty; Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 404 Not Found
Server: nginx
Date: Fri, 28 Dec 2012 08:37:31 GMT
<b>Content-Type: application/json; charset=utf-8</b>
Connection: close
Status: 404 Not Found
X-GitHub-Media-Type: github.beta
X-RateLimit-Remaining: 48
X-RateLimit-Limit: 60
Content-Length: 23
X-Content-Type-Options: nosniff
Cache-Control: 
</span>
<span class="repl-output">#(123 34 109 101 115 115 97 103 101 34 58 34 78 111 116 32 70 111 117 110 100 34 125)
404
((:SERVER . "nginx") (:DATE . "Fri, 28 Dec 2012 08:37:31 GMT") (:CONTENT-TYPE . "application/json; charset=utf-8")
 (:CONNECTION . "close") (:STATUS . "404 Not Found") (:X-GITHUB-MEDIA-TYPE . "github.beta") (:X-RATELIMIT-REMAINING . "48")
 (:X-RATELIMIT-LIMIT . "60") (:CONTENT-LENGTH . "23") (:X-CONTENT-TYPE-OPTIONS . "nosniff") (:CACHE-CONTROL . ""))
#&lt;PURI:URI https://api.github.com/repos/edicl/drakma/git/tags/tag-does-not-exist&gt;
#&lt;FLEXI-STREAMS:FLEXI-IO-STREAM {101C40C043}&gt;
T
"Not Found"</span>
<span class="repl-output">? </span><span class="repl-input">(<a href="http://weitz.de/flexi-streams/#octets-to-string" target="_new">flexi-streams:octets-to-string</a> *)</span>
<span class="repl-output">"{\"message\":\"Not Found\"}"</span></pre>
    
    <h4 xmlns=""><a name="ex-chunked-https">Chunked transfers and HTTPS</a></h4>
      <p>
        Request a page using the HTTPS protocol.  Also note that the
        server uses <a name="chunked" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1">chunked
        transfer encoding</a> for its reply
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(ql:quickload :cl-ppcre)</span>
<span class="repl-output">? </span><span class="repl-input">(cl-ppcre:scan-to-strings "(?s)You have.*your data."
                            (<a href="#http-request">drakma:http-request</a> "https://www.fortify.net/cgi/ssl_2.pl"))</span>
<span class="headers-out">GET /cgi/ssl_2.pl HTTP/1.1
Host: www.fortify.net
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:15:31 GMT
Server: Apache
Connection: close
<b>Transfer-Encoding: chunked</b>
Content-Type: text/html
</span>
<span class="repl-output">"You have connected to this web server using the RC4-SHA encryption cipher
 with a key length of 128 bits.
 &lt;p&gt;
 This is a high-grade encryption connection, regarded by most experts as being suitable
 for sending or receiving even the most sensitive or valuable information
 across a network.
 &lt;p&gt;
 In a crude analogy, using this cipher is similar to sending or storing your data inside
 a high quality safe - compared to an export-grade cipher which is similar to using
 a paper envelope to protect your data."
#()</span>
</pre>
    
    <h4 xmlns=""><a name="ex-fake-ua">Faking a user agent header</a></h4>
      <p>
        Some servers adapt their behavior according to the Browser
        that is used.  Drakma can claim to be i.e. MS Internet
        Explorer.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(cl-ppcre:scan-to-strings "&lt;h4&gt;.*" (<a href="#http-request">drakma:http-request</a> "http://whatsmyuseragent.com/" <a href="#arg-user-agent">:user-agent :explorer</a>))</span>
<span class="headers-out">GET / HTTP/1.1
Host: whatsmyuseragent.com
<b>User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727)</b>
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:23:50 GMT
Server: Apache
X-Powered-By: PHP/5.2.17
Connection: close
Transfer-Encoding: chunked
Content-Type: text/html
</span>
<span class="repl-output">"&lt;h4&gt;Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727)&lt;/h4&gt;"
#()</span>
</pre>
    
    <h4 xmlns=""><a name="ex-post-and-cookie">Posting data and using cookies</a></h4>
      <p>
        Drakma can send parameters in a POST request and knows how to
        deal with <a href="#cookie">cookies</a>.  Note how Drakma
        sends the cookie back in the second request.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(let ((cookie-jar (make-instance <a href="#cookie-jar">'drakma:cookie-jar</a>)))
    (<a href="#http-request">drakma:http-request</a> "http://www.phpsecurepages.com/test/test.php"
                         <a href="#arg-method">:method :post</a>
                         <a href="#arg-parameters">:parameters '(("entered_login" . "test")
                                       ("entered_password" . "test"))</a>
                         <a href="#arg-cookie-jar">:cookie-jar cookie-jar</a>)
    (<a href="#http-request">drakma:http-request</a> "http://www.phpsecurepages.com/test/test2.php"
                         <a href="#arg-cookie-jar">:cookie-jar cookie-jar</a>)
    (<a href="#cookie-jar-cookies">drakma:cookie-jar-cookies</a> cookie-jar))</span>
<span class="headers-out">POST /test/test.php HTTP/1.1
Host: www.phpsecurepages.com
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 40
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:25:13 GMT
Server:  
X-Powered-By: PHP/5.2.17
<b>Set-Cookie: PHPSESSID=vijk3706eojs7n8u5cdpi3ju05; path=/</b>
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
X-Powered-By: PleskLin
Content-Length: 4479
Connection: close
Content-Type: text/html
</span>
<span class="headers-out">GET /test/test2.php HTTP/1.1
Host: www.phpsecurepages.com
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
<b>Cookie: PHPSESSID=vijk3706eojs7n8u5cdpi3ju05</b>
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:25:16 GMT
Server:  
X-Powered-By: PHP/5.2.17
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
X-Powered-By: PleskLin
Content-Length: 4479
Connection: close
Content-Type: text/html
</span>
<span class="repl-output">(#&lt;COOKIE PHPSESSID=vijk3706eojs7n8u5cdpi3ju05; path=/; domain=www.phpsecurepages.com&gt;)</span>
</pre>
    
    <h4 xmlns=""><a name="ex-reuse-connection">Reusing a connection to a server</a></h4>
      <p>
        Drakma can <a name="re-use">use</a> a connection to a server for multiple requests.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(let ((stream (nth-value 4 (<a href="#http-request">drakma:http-request</a> "http://www.lispworks.com/" <a href="#arg-close">:close nil</a>))))
    (nth-value 2 (<a href="#http-request">drakma:http-request</a> "http://www.lispworks.com/success-stories/index.html"
                                      <a href="#arg-stream">:stream stream</a>)))</span>
<span class="headers-out">GET / HTTP/1.1
Host: www.lispworks.com
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:25:56 GMT
Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/1.0.1c mod_apreq2-20051231/2.6.0 mod_perl/2.0.5 Perl/v5.8.9
Last-Modified: Tue, 20 Nov 2012 12:27:40 GMT
ETag: "336280-28eb-4ceec5c1f4700"
Accept-Ranges: bytes
Content-Length: 10475
Content-Type: text/html
</span>
<span class="headers-out">GET /success-stories/index.html HTTP/1.1
Host: www.lispworks.com
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
<b>Connection: close</b>
</span>
<span class="headers-in">HTTP/1.1 200 OK
Date: Sun, 09 Dec 2012 08:25:56 GMT
Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/1.0.1c mod_apreq2-20051231/2.6.0 mod_perl/2.0.5 Perl/v5.8.9
Last-Modified: Tue, 20 Nov 2012 12:28:52 GMT
ETag: "336386-2940-4ceec6069e900"
Accept-Ranges: bytes
Content-Length: 10560
<b>Connection: close</b>
Content-Type: text/html
</span>
<span class="repl-output">((:DATE . "Sun, 09 Dec 2012 08:25:56 GMT")
 (:SERVER . "Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/1.0.1c mod_apreq2-20051231/2.6.0 mod_perl/2.0.5 Perl/v5.8.9")
 (:LAST-MODIFIED . "Tue, 20 Nov 2012 12:28:52 GMT") (:ETAG . "\"336386-2940-4ceec6069e900\"") (:ACCEPT-RANGES . "bytes")
 (:CONTENT-LENGTH . "10560") (:CONNECTION . "close") (:CONTENT-TYPE . "text/html"))</span>
</pre>
    
    <h4 xmlns=""><a name="ex-basic-auth">Basic Authorization</a></h4>
      <p>
        Drakma supports basic authorization.  In this example, we use
        a locally running <a href="http://weitz.de/hunchentoot">Hunchentoot</a> server.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(ql:quickload :hunchentoot-test)</span>
<span class="repl-output">To load "hunchentoot-test":
  Load 4 ASDF systems:
    cl-ppcre cl-who drakma hunchentoot
  Install 1 Quicklisp release:
    hunchentoot
...
; Loading "hunchentoot-test"

(:HUNCHENTOOT-TEST)
? </span><span class="repl-input">(hunchentoot:start (make-instance 'hunchentoot:easy-acceptor :port 4242))</span>
<span class="repl-output">#&lt;EASY-ACCEPTOR (host *, port 4242)&gt;
? </span><span class="repl-input">(nth-value 1 (<a href="#http-request">drakma:http-request</a> "http://localhost:4242/hunchentoot/test/authorization.html"))</span>
<span class="headers-out">GET /hunchentoot/test/authorization.html HTTP/1.1
Host: localhost:4242
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="repl-output">127.0.0.1 - [2012-12-09 09:27:40] "GET /hunchentoot/test/authorization.html HTTP/1.1" 401 543 "-" "Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)"</span>
<span class="headers-in">HTTP/1.1 <b>401 Authorization Required</b>
Content-Length: 543
Date: Sun, 09 Dec 2012 08:27:40 GMT
Server: Hunchentoot 1.2.5
Connection: Close
Www-Authenticate: Basic realm="Hunchentoot"
Content-Type: text/html; charset=iso-8859-1
</span>
<span class="repl-output">401
? </span><span class="repl-input">(nth-value 1 (<a href="#http-request">drakma:http-request</a> "http://localhost:4242/hunchentoot/test/authorization.html"
                                    <a href="#arg-basic-authorization">:basic-authorization '("nanook" "igloo")</a>))</span>
<span class="headers-out">GET /hunchentoot/test/authorization.html HTTP/1.1
Host: localhost:4242
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
<b>Authorization: Basic bmFub29rOmlnbG9v</b>
Accept: */*
Connection: close
</span>
<span class="repl-output">127.0.0.1 nanook [2012-12-09 09:28:15] "GET /hunchentoot/test/authorization.html HTTP/1.1" 200 907 "-" "Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)"</span>
<span class="headers-in">HTTP/1.1 200 OK
Content-Length: 907
Date: Sun, 09 Dec 2012 08:28:15 GMT
Server: Hunchentoot 1.2.5
Connection: Close
Content-Type: text/html; charset=utf-8
</span>
<span class="repl-output">200</span>
</pre>
    
    <h4 xmlns=""><a name="ex-response-stream">Reading the response from a stream</a></h4>
      <p>
        Drakma can return a stream to the application so that the
        reply is not completely buffered in memory first.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(let ((stream (<a href="#http-request">drakma:http-request</a> "https://api.github.com/orgs/edicl/public_members"
                                      <b>:want-stream t</b>)))
    (setf (<a href="http://weitz.de/flexi-streams/#flexi-stream-external-format" target="_new">flexi-streams:flexi-stream-external-format</a> stream) :utf-8)
    (<a href="http://common-lisp.net/project/yason/#parse" target="_new">yason:parse</a> stream :object-as :plist))</span>
<span class="headers-out">GET /orgs/edicl/public_members HTTP/1.1
Host: api.github.com
User-Agent: Drakma/1.3.0 (SBCL 1.1.1.31.master.2-9fac43f-dirty; Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
</span>
<span class="headers-in">HTTP/1.1 200 OK
Server: nginx
Date: Fri, 28 Dec 2012 10:27:34 GMT
Content-Type: application/json; charset=utf-8
Connection: close
Status: 200 OK
Last-Modified: Sat, 22 Dec 2012 18:39:14 GMT
X-Content-Type-Options: nosniff
X-RateLimit-Limit: 60
X-GitHub-Media-Type: github.beta
Vary: Accept
Content-Length: 1899
Cache-Control: public, max-age=60, s-maxage=60
ETag: "66a5dd35e79146a53029a1807293f9d3"
X-RateLimit-Remaining: 56
</span>
<span class="repl-output">(("type" "User" "repos_url" "https://api.github.com/users/hanshuebner/repos" "followers_url"
  "https://api.github.com/users/hanshuebner/followers" "login" "hanshuebner" "gists_url"
  "https://api.github.com/users/hanshuebner/gists{/gist_id}" "following_url"
  "https://api.github.com/users/hanshuebner/following" "events_url"
  "https://api.github.com/users/hanshuebner/events{/privacy}" "organizations_url"
  "https://api.github.com/users/hanshuebner/orgs" "received_events_url"
  "https://api.github.com/users/hanshuebner/received_events" "url"
  "https://api.github.com/users/hanshuebner" "avatar_url"
  "https://secure.gravatar.com/avatar/280d76aa82179ae04550534649de1e6e?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"
  "subscriptions_url" "https://api.github.com/users/hanshuebner/subscriptions" "starred_url"
  "https://api.github.com/users/hanshuebner/starred{/owner}{/repo}" "id" 108751 "gravatar_id"
  "280d76aa82179ae04550534649de1e6e")
 ("type" "User" "repos_url" "https://api.github.com/users/nhabedi/repos" "followers_url"
  "https://api.github.com/users/nhabedi/followers" "login" "nhabedi" "gists_url"
  "https://api.github.com/users/nhabedi/gists{/gist_id}" "following_url"
  "https://api.github.com/users/nhabedi/following" "events_url"
  "https://api.github.com/users/nhabedi/events{/privacy}" "organizations_url"
  "https://api.github.com/users/nhabedi/orgs" "received_events_url"
  "https://api.github.com/users/nhabedi/received_events" "url"
  "https://api.github.com/users/nhabedi" "avatar_url"
  "https://secure.gravatar.com/avatar/24c09c7b0b2c0481283d854bacdd7926?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"
  "subscriptions_url" "https://api.github.com/users/nhabedi/subscriptions" "starred_url"
  "https://api.github.com/users/nhabedi/starred{/owner}{/repo}" "id" 537618 "gravatar_id"
  "24c09c7b0b2c0481283d854bacdd7926"))</span>
</pre>
    
    <h4 xmlns=""><a name="ex-assemble-request-content">Piecemeal assembly of request contents</a></h4>
      <p>
        Request contents can be assembled from various sources, and
        chunked encoding can be used by request bodies.  Many servers
        do not support chunked encoding for request bodies, though.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(let ((temp-file (ensure-directories-exist #p"/tmp/quux.txt"))
        (continuation (<a href="#http-request">drakma:http-request</a> "http://localhost:4242/hunchentoot/test/parameter_latin1_post.html"
                                           <a href="#arg-method">:method :post</a>
                                           <a href="#arg-content">:content :continuation</a>)))
    (funcall continuation "foo=" t)
    (funcall continuation (list (char-code #\z) (char-code #\a)) t)
    (funcall continuation (lambda (stream)
                            (write-char #\p stream)) t)
    (with-open-file (out temp-file
                         :direction :output
                         :if-does-not-exist :create
                         :if-exists :supersede)
      (write-string "p" out))
    (funcall continuation temp-file t)
    (cl-ppcre:scan-to-strings "zappzerapp" (funcall continuation "zerapp")))</span>
<span class="headers-out">POST /hunchentoot/test/parameter_latin1_post.html HTTP/1.1
Host: localhost:4242
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
Content-Type: application/x-www-form-urlencoded
<b>Transfer-Encoding: chunked</b>
</span>
<span class="repl-output">127.0.0.1 - [2012-12-09 10:06:44] "POST /hunchentoot/test/parameter_latin1_post.html HTTP/1.1" 200 1312 "-" "Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)"</span>
<span class="headers-in">HTTP/1.1 200 OK
Content-Length: 1312
Date: Sun, 09 Dec 2012 09:06:44 GMT
Server: Hunchentoot 1.2.5
Connection: Close
Last-Modified: Sun, 09 Dec 2012 09:06:44 GMT
Pragma: no-cache
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Content-Type: text/html; charset=ISO-8859-1
</span>
<span class="repl-output">"zappzerapp"
#()</span>
</pre>
    
    <h4 xmlns=""><a name="ex-partial-transfers">Partial transfers</a></h4>
      <p>
        <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35" target="_new">Partial transfers</a> of resources are possible.
      </p>
      <pre><span class="repl-output">? </span><span class="repl-input">(cl-ppcre:regex-replace-all
   "&lt;.*?&gt;"
   (format nil "~A~%~A"
           (<a href="#http-request">drakma:http-request</a> "http://members.shaw.ca/mitb/hunchentoot.html"
                                <a href="#arg-range">:range '(998 1034)</a>)
           (<a href="#http-request">drakma:http-request</a> "http://members.shaw.ca/mitb/hunchentoot.html"
                                <a href="#arg-range">:range '(1213 1249)</a>))
   "")</span>
<span class="headers-out">GET /mitb/hunchentoot.html HTTP/1.1
Host: members.shaw.ca
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
<b>Range: bytes=998-1034</b>
</span>
<span class="headers-in">HTTP/1.1 206 Partial Content
Date: Sun, 09 Dec 2012 09:16:16 GMT
Server: Apache/2.2.20 (Unix) mod_ldap_userdir/1.1.17
Last-Modified: Wed, 14 Mar 2012 23:22:04 GMT
ETag: "3b7eed-3238-4bb3c3e453f00"
Accept-Ranges: bytes
Content-Length: 37
<b>Content-Range: bytes 998-1034/12856</b>
Content-Type: text/html
Connection: close
</span>
<span class="headers-out">GET /mitb/hunchentoot.html HTTP/1.1
Host: members.shaw.ca
User-Agent: Drakma/1.3.0 (Clozure Common Lisp Version 1.8-r15286M  (DarwinX8664); Darwin; 12.2.0; http://weitz.de/drakma/)
Accept: */*
Connection: close
<b>Range: bytes=1213-1249</b>
</span>
<span class="headers-in">HTTP/1.1 206 Partial Content
Date: Sun, 09 Dec 2012 09:16:16 GMT
Server: Apache/2.2.20 (Unix) mod_ldap_userdir/1.1.17
Last-Modified: Wed, 14 Mar 2012 23:22:04 GMT
ETag: "3b7eed-3238-4bb3c3e453f00"
Accept-Ranges: bytes
Content-Length: 37
<b>Content-Range: bytes 1213-1249/12856</b>
Content-Type: text/html
</span>
<span class="repl-output">"DRAKMA (Queen of Cosmic Greed)
HUNCHENTOOT (The Giant Spider)"
T</span>
</pre>
    
  

  <h3 xmlns=""><a class="none" name="install">Download and Installation</a></h3>
    <p>
      Drakma depends on a number of open source libraries, so the
      preferred method to download, compile and load it is via <a href="http://www.quicklisp.org/">Quicklisp</a>.  Drakma's
      current version number is 2.0.4.
    </p>
    <p>
      The canonical location for the latest version of Drakma is <a href="http://weitz.de/files/drakma.tar.gz">http://weitz.de/files/drakma.tar.gz</a>.
    </p>
  

  <h3 xmlns=""><a class="none" name="patches">Development and patches</a></h3>
    <p>
      The development version of Drakma can be found <a href="https://github.com/edicl/drakma" target="_new">on
      github</a>.  Please use the github issue tracking system to
      submit bug reports.  Patches are welcome, please use <a href="https://github.com/edicl/drakma/pulls">GitHub pull
      requests</a>.  If you want to make a change, please <a href="http://weitz.de/patches.html" target="_new">read this
      first</a>.
    </p>
  

  <h3 xmlns=""><a class="none" name="dictionary">The Drakma dictionary</a></h3>

    <h4 xmlns=""><a name="dict-request">Requests</a></h4>

      <p>
        The <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> function is the heart of
        Drakma.  It is used to send requests to web servers and will
        either return the message body of the server's reply or (if
        the user so wishes) a stream one can read from.  The wealth of
        keyword parameters might look a bit intimidating first, but
        you will rarely need more than two or three of them - the
        default behavior of Drakma is (hopefully) designed to do The
        Right Thing[TM] in most cases.
      </p>
      <p>
        You can use the <code xmlns=""><a href="#*header-stream*">*HEADER-STREAM*</a></code> variable
        to debug requests handled by Drakma in a way similar to <a href="http://livehttpheaders.mozdev.org/">LiveHTTPHeaders</a>.
      </p>

      <p xmlns=""><a class="none" name="http-request"></a><clix:special-definition xmlns:clix="http://bknr.net/clixdoc">
          [Function]<br xmlns="http://www.w3.org/1999/xhtml"></br>
          <b xmlns="http://www.w3.org/1999/xhtml">http-request</b> <i xmlns="http://www.w3.org/1999/xhtml">uri</i><div xmlns="http://www.w3.org/1999/xhtml" class="arglist-spacer">&amp;rest args</div>
          <div xmlns="http://www.w3.org/1999/xhtml" class="arglist-spacer">&amp;key
            <a href="#arg-protocol">protocol</a>
            <a href="#arg-method">method</a>
            <a href="#arg-force-ssl">force-ssl</a>
            <a href="#arg-certificate">certificate</a>
            <a href="#arg-key">key</a>
            <a href="#arg-certificate-password">certificate-password</a>
            <a href="#arg-verify">verify</a>
            <a href="#arg-max-depth">max-depth</a>
            <a href="#arg-ca-file">ca-file</a>
            <a href="#arg-ca-directory">ca-directory</a>
            <a href="#arg-parameters">parameters</a>
            <a href="#arg-url-encoder">url-encoder</a>
            <a href="#arg-content">content</a>
            <a href="#arg-content-type">content-type</a>
            <a href="#arg-content-length">content-length</a>
            <a href="#arg-form-data">form-data</a>
            <a href="#arg-cookie-jar">cookie-jar</a>
            <a href="#arg-basic-authorization">basic-authorization</a>
            <a href="#arg-user-agent">user-agent</a>
            <a href="#arg-accept">accept</a>
            <a href="#arg-range">range</a>
            <a href="#arg-proxy">proxy</a>
            <a href="#arg-proxy-basic-authorization">proxy-basic-authorization</a>
            <a href="#arg-real-host">real-host</a>
            <a href="#arg-additional-headers">additional-headers</a>
            <a href="#arg-redirect">redirect</a>
            <a href="#arg-auto-referer">auto-referer</a>
            <a href="#arg-keep-alive">keep-alive</a>
            <a href="#arg-close">close</a>
            <a href="#arg-external-format-out">external-format-out</a>
            <a href="#arg-external-format-in">external-format-in</a>
            <a href="#arg-force-binary">force-binary</a>
            <a href="#arg-want-stream">want-stream</a>
            <a href="#arg-stream">stream</a>
            <a href="#arg-preserve-uri">preserve-uri</a>
            <a href="#arg-connection-timeout">connection-timeout</a>
            <a href="#arg-deadline">deadline</a>
          </div>
          <div xmlns="http://www.w3.org/1999/xhtml" class="arglist-spacer">
            =&gt; body-or-stream<sup>0</sup>, status-code<sup>1</sup>,
            headers<sup>2</sup>, uri<sup>3</sup>, stream<sup>4</sup>,
            <a href="#arg-want-stream">must-close<sup>5</sup></a>,
            reason-phrase<sup>6</sup>
          </div>
        </clix:special-definition><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Sends an <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP</a>
            request to a web server and returns its reply.
            <code xmlns=""><i>uri</i></code> is where the request is sent to,
            and it is either a string denoting a uniform resource
            identifier or a <code>PURI:URI</code> object.  The scheme
            of <code xmlns=""><i>uri</i></code> must be `http' or `https'.
            The function returns SEVEN values - the body of the
            reply<sup>0</sup> (but see below), the status
            code<sup>1</sup> as an integer, an alist of the
            headers<sup>2</sup> sent by the server where for each
            element the car (the name of the header) is a keyword and
            the cdr (the value of the header) is a string, the
            uri<sup>3</sup> the reply comes from (which might be
            different from the <code xmlns=""><i>uri</i></code> the request
            was sent to in case of redirects), the stream<sup>4</sup>
            the reply was read from, a generalized boolean<sup>5</sup>
            which denotes whether the stream should be closed (and
            which you can usually ignore), and finally the reason
            phrase<sup>6</sup> from the status line as a string.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-protocol"></a>
            <code xmlns=""><i>protocol</i></code> is the HTTP protocol version
            which is going to be used in the request line.  It must be
            one of the keywords <code>:HTTP/1.0</code> or
            <code>:HTTP/1.1</code>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-method"></a>
            <code xmlns=""><i>method</i></code> is the method used in the
            request line, a keyword (like <code>:GET</code> or
            <code>:HEAD</code>) denoting a valid HTTP/1.1 or WebDAV
            request method, or <code>:REPORT</code>, as described in
            the Versioning Extensions to WebDAV.  Additionally, you
            can also use the pseudo method <code>:OPTIONS*</code>
            which is like <code>:OPTIONS</code> but means that an
            "OPTIONS *" request line will be sent, i.e. the
            <code xmlns=""><i>uri</i></code>'s path and query parts will be
            ignored.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml"><a name="arg-force-ssl"></a>
            If <code xmlns=""><i>force-ssl</i></code> is true, SSL will be
            attached to the socket stream which connects Drakma with
            the web server.  Usually, you don't have to provide this
            argument, as SSL will be attached anyway if the scheme of
            <code xmlns=""><i>uri</i></code> is `https'.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml"><a name="arg-certificate"></a><a name="arg-certificate-password"></a><a name="arg-key"></a>
          <code xmlns=""><i>certificate</i></code> is the file name of the PEM
          encoded client certificate to present to the server when
          making a SSL connection.  <code xmlns=""><i>key</i></code> specifies
          the file name of the PEM encoded private key matching the
          certificate.  <code xmlns=""><i>certificate-password</i></code>
          specifies the pass phrase to use to decrypt the private key.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-verify"></a>
            <code xmlns=""><i>verify</i></code> can be specified to force
            verification of the certificate that is presented by the
            server in an SSL connection.  It can be specified either
            as <code>NIL</code> if no check should be performed,
            <code>:OPTIONAL</code> to verify the server's certificate
            if it presented one or <code>:REQUIRED</code> to verify
            the server's certificate and fail if an invalid or no
            certificate was presented.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-max-depth"></a>
            <code xmlns=""><i>max-depth</i></code> can be specified to change
            the maximum allowed certificate signing depth that is
            accepted.  The default is 10.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-ca-file"></a>
            <a name="arg-ca-directory"></a>
            <code xmlns=""><i>ca-file</i></code> and
            <code xmlns=""><i>ca-directory</i></code> can be specified to set
            the certificate authority bundle file or directory to use
            for certificate validation.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            The <code xmlns=""><i>certificate</i></code>,
            <code xmlns=""><i>key</i></code>,
            <code xmlns=""><i>certificate-password</i></code>,
            <code xmlns=""><i>verify</i></code>,
            <code xmlns=""><i>max-depth</i></code>,
            <code xmlns=""><i>ca-file</i></code> and
            <code xmlns=""><i>ca-directory</i></code> parameters are ignored
            for non-SSL requests.  They are also ignored on LispWorks.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-parameters"></a>
            <a name="arg-form-data"></a>
            <code xmlns=""><i>parameters</i></code> is an alist of name/value
            pairs (the car and the cdr each being a string) which
            denotes the parameters which are added to the query part
            of the URL or (in the case of a POST request) comprise the
            body of the request.  (But see
            <code xmlns=""><i>content</i></code> below.)  The values can also
            be <code>NIL</code> in which case only the name (without
            an equal sign) is used in the query string.  The
            name/value pairs are URL-encoded using the FLEXI-STREAMS
            external format <code xmlns=""><i>external-format-out</i></code>
            before they are sent to the server unless
            <code xmlns=""><i>form-data</i></code> is true in which case the
            POST request body is sent as `multipart/form-data' using
            <code xmlns=""><i>external-format-out</i></code>.  The values of
            the <code xmlns=""><i>parameters</i></code> alist can also be
            pathnames, open binary input streams, unary functions, or
            lists where the first element is of one of the former
            types.  These values denote files which should be sent as
            part of the request body.  If files are present in
            <code xmlns=""><i>parameters</i></code>, the content type of the
            request is always `multipart/form-data'.  If the value is
            a list, the part of the list behind the first element is
            treated as a plist which can be used to specify a content
            type and/or a filename for the file, i.e. such a value
            could look like, e.g., <tt>(#p"/tmp/my_file.doc"
            :content-type "application/msword" :filename
            "upload.doc")</tt>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-url-encoder"></a>
            <code xmlns=""><i>url-encoder</i></code> specifies a custom URL
            encoder function which will be used by drakma to
            URL-encode parameter names and values.  It needs to be a
            function of two arguments.  The arguments are the string
            to encode and the external format to use (as accepted by
            FLEXI-STREAMS:STRING-TO-OCTETS).  The return value must be
            the URL-encoded string.  This can be used if specific
            encoding rules are required.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-content"></a>
            <a name="arg-external-format-out"></a>
            <code xmlns=""><i>content</i></code>, if not <code>NIL</code>, is
            used as the request body - <code xmlns=""><i>parameters</i></code>
            is ignored in this case.  <code xmlns=""><i>content</i></code> can
            be a string, a sequence of octets, a pathname, an open
            binary input stream, or a function designator.  If
            <code xmlns=""><i>content</i></code> is a sequence, it will be
            directly sent to the server (using
            <code xmlns=""><i>external-format-out</i></code> in the case of
            strings).  If <code xmlns=""><i>content</i></code> is a pathname,
            the binary contents of the corresponding file will be sent
            to the server.  If <code xmlns=""><i>content</i></code> is a
            stream, everything that can be read from the stream until
            EOF will be sent to the server.  If
            <code xmlns=""><i>content</i></code> is a function designator, the
            corresponding function will be called with one argument,
            the stream to the server, to which it should send data.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            Finally, <code xmlns=""><i>content</i></code> can also be the
            keyword <code>:CONTINUATION</code> in which case
            <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> returns only one value -
            a `continuation' function.  This function has one required
            argument and one optional argument.  The first argument
            will be interpreted like <code xmlns=""><i>content</i></code>
            above (but it cannot be a keyword), i.e. it will be sent
            to the server according to its type.  If the second
            argument is true, the continuation function can be called
            again to send more content, if it is <code>NIL</code> the
            continuation function returns what
            <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> would have returned.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>content</i></code> is a sequence, Drakma will
            use LENGTH to determine its length and will use the result
            for the `Content-Length' header sent to the server.  You
            can overwrite this with the
            <code xmlns=""><i>content-length</i></code> parameter (a
            non-negative integer) which you can also use for the cases
            where Drakma can't or won't determine the content length
            itself.  You can also explicitly provide a
            <code xmlns=""><i>content-length</i></code> argument of
            <code>NIL</code> which will imply that no `Content-Length'
            header will be sent in any case.  If no `Content-Length'
            header is sent, Drakma will use chunked encoding to send
            the content body.  Note that this will not work with older
            web servers.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-content-length"></a>
            Providing a true <code xmlns=""><i>content-length</i></code>
            argument which is not a non-negative integer means that
            Drakma /must/ build the request body in RAM and compute
            the content length even if it would have otherwise used
            chunked encoding, for example in the case of file uploads.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-content-type"></a>
            <code xmlns=""><i>content-type</i></code> is the corresponding
            `Content-Type' header to be sent and will be ignored
            unless <code xmlns=""><i>content</i></code> is provided as well.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            Note that a query already contained in
            <code xmlns=""><i>uri</i></code> will always be sent with the
            request line anyway in addition to other parameters sent
            by Drakma.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-cookie-jar"></a>
            <code xmlns=""><i>cookie-jar</i></code> is a cookie jar containing
            cookies which will potentially be sent to the server (if
            the domain matches, if they haven't expired, etc.) - this
            cookie jar will be modified according to the `Set-Cookie'
            header(s) sent back by the server.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-basic-authorization"></a>
            <code xmlns=""><i>basic-authorization</i></code>, if not
            <code>NIL</code>, should be a list of two strings
            (username and password) which will be sent to the server
            for basic authorization.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-user-agent"></a>
            <code xmlns=""><i>user-agent</i></code>, if not <code>NIL</code>,
            denotes which `User-Agent' header will be sent with the
            request.  It can be one of the keywords
            <code>:DRAKMA</code>, <code>:FIREFOX</code>,
            <code>:EXPLORER</code>, <code>:OPERA</code>, or
            <code>:SAFARI</code> which denote the current version of
            Drakma or, in the latter four cases, a fixed string
            corresponding to a more or less recent (as of August 2006)
            version of the corresponding browser.  Or it can be a
            string which is used directly.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-accept"></a>
            <code xmlns=""><i>accept</i></code>, if not <code>NIL</code>,
            specifies the contents of the `Accept' header sent.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-range"></a>
            <code xmlns=""><i>range</i></code> optionally specifies a subrange
            of the resource to be requested.  It must be specified as
            a list of two integers which indicate the start and
            (inclusive) end offset of the requested range, in bytes
            (i.e. octets).
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-proxy"></a>
            <a name="arg-proxy-basic-authorization"></a>
            If <code xmlns=""><i>proxy</i></code> is not <code>NIL</code>, it
            should be a string denoting a proxy server through which
            the request should be sent.  Or it can be a list of two
            values - a string denoting the proxy server and an integer
            denoting the port to use (which will default to 80
            otherwise).  Defaults to
            <code xmlns=""><i>*default-http-proxy*</i></code>.
            <code xmlns=""><i>proxy-basic-authorization</i></code> is used
            like <code xmlns=""><i>basic-authorization</i></code>, but for the
            proxy, and only if <code xmlns=""><i>proxy</i></code> is true.  If
            the host portion of the uri is present in the
            <code xmlns=""><a href="#*no-proxy-domains*">*NO-PROXY-DOMAINS*</a></code> or the
            <code xmlns=""><i>NO-PROXY-DOMAINS</i></code> list then the proxy
            setting will be ignored for this request.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>NO-PROXY-DOMAINS</i></code> is set then it
            will supersede the <code xmlns=""><a href="#*no-proxy-domains*">*NO-PROXY-DOMAINS*</a></code>
            variable. Inserting domains into this list will allow them
            to ignore the proxy setting.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-real-host"></a>
            If <code xmlns=""><i>real-host</i></code> is not <code>NIL</code>,
            request is sent to the denoted host instead of the
            <code xmlns=""><i>uri</i></code> host.  When specified,
            <code xmlns=""><i>real-host</i></code> supersedes
            <code xmlns=""><i>proxy</i></code>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-additional-headers"></a>
            <code xmlns=""><i>additional-headers</i></code> is a name/value
            alist of additional HTTP headers which should be sent with
            the request.  Unlike in <code xmlns=""><i>parameters</i></code>,
            the cdrs can not only be strings but also designators for
            unary functions (which should in turn return a string) in
            which case the function is called each time the header is
            written.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-redirect"></a>
            <a name="arg-auto-referer"></a>
            If <code xmlns=""><i>redirect</i></code> is not <code>NIL</code>,
            it must be a non-negative integer or T.  If
            <code xmlns=""><i>redirect</i></code> is true, Drakma will follow
            redirects (return codes 301, 302, 303, or 307) unless
            <code xmlns=""><i>redirect</i></code> is 0.  If
            <code xmlns=""><i>redirect</i></code> is an integer, it will be
            decreased by 1 with each redirect.  Furthermore, if
            <code xmlns=""><i>auto-referer</i></code> is true when following
            redirects, Drakma will populate the `Referer' header with
            the <code xmlns=""><i>uri</i></code> that triggered the
            redirection, overwriting an existing `Referer' header (in
            <code xmlns=""><i>additional-headers</i></code>) if necessary.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-keep-alive"></a>
            <a name="arg-close"></a>
            If <code xmlns=""><i>keep-alive</i></code> is T, the server will
            be asked to keep the connection alive, i.e. not to close
            it after the reply has been sent.  (Note that this not
            necessary if both the client and the server use HTTP 1.1.)
            If <code xmlns=""><i>close</i></code> is T, the server is
            explicitly asked to close the connection after the reply
            has been sent.  <code xmlns=""><i>keep-alive</i></code> and
            <code xmlns=""><i>close</i></code> are obviously mutually
            exclusive.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-external-format-in"></a>
            <a name="arg-force-binary"></a>
            If the message body sent by the server has a text content
            type, Drakma will try to return it as a Lisp string.
            It'll first check if the `Content-Type' header denotes an
            encoding to be used, or otherwise it will use the
            <code xmlns=""><i>external-format-in</i></code> argument.  The
            body is decoded using FLEXI-STREAMS.  If FLEXI-STREAMS
            doesn't know the external format, the body is returned as
            an array of octets.  If the body is empty, Drakma will
            return <code>NIL</code>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            If the message body doesn't have a text content type or if
            <code xmlns=""><i>force-binary</i></code> is true, the body is
            always returned as an array of octets.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-want-stream"></a>
            If <code xmlns=""><i>want-stream</i></code> is true, the message
            body is NOT read and instead the (open) socket stream is
            returned as the first return value.  If the sixth value of
            <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> is true, the stream
            should be closed (and not be re-used) after the body has
            been read.  The stream returned is a <a href="http://weitz.de/flexi-streams/">flexi-stream</a>
            with a <a href="http://weitz.de/chunga/" target="_new">chunked stream</a> as its underlying stream.
            If you want to read binary data from this stream, read
            from the underlying stream which you can get with
            FLEXI-STREAM-STREAM.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-stream"></a>
            Drakma will usually create a new socket connection for
            each HTTP request.  However, you can use the
            <code xmlns=""><i>stream</i></code> argument to provide an open
            socket stream which should be re-used.
            <code xmlns=""><i>stream</i></code> MUST be a stream returned by a
            previous invocation of <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>
            where the sixth return value wasn't true.  Obviously, it
            must also be connected to the correct server and at the
            right position (i.e. the message body, if any, must have
            been read).  Drakma will NEVER attach SSL to a stream
            provided as the <code xmlns=""><i>stream</i></code> argument.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-connection-timeout"></a>
            <code xmlns=""><i>connection-timeout</i></code> is the time (in
            seconds) Drakma will wait until it considers an attempt to
            connect to a server as a failure. It is supported only on
            some platforms (currently abcl, clisp, LispWorks, mcl,
            openmcl and sbcl). READ-TIMEOUT and WRITE-TIMEOUT are the
            read and write timeouts (in seconds) for the socket stream
            to the server.  All three timeout arguments can also be
            <code>NIL</code> (meaning no timeout), and they don't
            apply if an existing stream is re-used.  READ-TIMEOUT
            argument is only available for LispWorks, WRITE-TIMEOUT is
            only available for LispWorks 5.0 or higher.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-deadline"></a>
            <code xmlns=""><i>deadline</i></code>, a time in the future,
            specifies the time until which the request should be
            finished.  The deadline is specified in internal time
            units.  If the server fails to respond until that time, a
            COMMUNICATION-DEADLINE-EXPIRED condition is signalled.
            <code xmlns=""><i>deadline</i></code> is only available on CCL 1.2
            and later.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <a name="arg-preserve-uri"></a>
            If <code xmlns=""><i>preserve-uri</i></code> is not
            <code>NIL</code>, the given <code xmlns=""><i>uri</i></code> will
            not be processed. This means that the
            <code xmlns=""><i>uri</i></code> will be sent as-is to the remote
            server and it is the responsibility of the client to make
            sure that all parameters are encoded properly. Note that
            if this parameter is given, and the request is not a POST
            with a content-type of `multipart/form-data',
            <code xmlns=""><i>parameters</i></code> will not be used.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>decode-content</i></code> is not
            <code>NIL</code>, then the content will automatically be
            decoded according to any encodings specified in the
            Content-Encoding header. The actual decoding is done by
            the <code xmlns=""><a href="#decode-stream">decode-stream</a></code> generic function,
            and you can implement new methods to support additional
            encodings.  Any encodings in Transfer-Encoding, such as
            chunking, are always performed.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="parameter-present-p"></a>
          [Function]
          <br><b>parameter-present-p</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">name parameters</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">boolean</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>parameters</i></code> is an alist of
            parameters as returned by, for example,
            READ-TOKENS-AND-PARAMETERS and <code xmlns=""><i>name</i></code>
            is a string naming a parameter, this function returns the
            full parameter (name and value) - or <code>NIL</code> if
            it's not in <code xmlns=""><i>parameters</i></code>.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="parameter-value"></a>
          [Function]
          <br><b>parameter-value</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">name parameters</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or string null)</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>parameters</i></code> is an alist of
            parameters as returned by, for example,
            READ-TOKENS-AND-PARAMETERS and <code xmlns=""><i>name</i></code>
            is a string naming a parameter, this function returns the
            value of this parameter - or <code>NIL</code> if it's not
            in <code xmlns=""><i>parameters</i></code>.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="url-encode"></a>
          [Function]
          <br><b>url-encode</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">string external-format</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">string</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Returns a URL-encoded version of the string
            <code xmlns=""><i>string</i></code> using the external format
            <code xmlns=""><i>external-format</i></code>.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="decode-stream"></a>
          [Function]
          <br><b>decode-stream</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">encoding-type stream</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">stream</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Generic function to decode a stream.  This is a generic
            function which decodes the stream based on the
            encoding-type.  If a response contains one or more
            transfer or content encodings, then decode-stream is
            called for each encoding type in the correct order to
            properly decode the stream to its original content.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            <code xmlns=""><i>encoding-type</i></code> will be a keyword
            created by upcasing and interning the encoding type from
            the header.  <code xmlns=""><i>stream</i></code> will be the
            stream that needs to be
            decoded. <code xmlns=""><a href="#decode-stream">decode-stream</a></code> returns a new
            stream from which you can read the decoded data.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*body-format-function*"></a>
      [Special variable]
      <br><b>*body-format-function*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            A function which determines whether the content body
            returned by the server is text and should be treated as
            such or not.  The function is called after the request
            <code xmlns=""><a href="#headers">headers</a></code> have been read and it must
            accept two arguments, <code><i>headers</i></code> and
            <code><i>external-format-in</i></code>, where
            <code><i>headers</i></code> is like the third return value
            of <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> while
            <code><i>external-format-in</i></code> is the
            <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> argument of the same
            name.  It should return <code>NIL</code> if the body
            should be regarded as binary content, or a <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a>
            external format (which will be used to read the body)
            otherwise.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            This function will only be called if the <a href="#arg-force-binary"><code><i>force-binary</i></code></a>
            argument to <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> is
            <code>NIL</code>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            The initial value of this variable is a function which
            uses <code xmlns=""><a href="#*text-content-types*">*TEXT-CONTENT-TYPES*</a></code> to
            determine whether the body is text and then proceeds as
            described in the <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>
            documentation entry.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*default-http-proxy*"></a>
      [Special variable]
      <br><b>*default-http-proxy*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
	    HTTP proxy to be used as default for the proxy keyword
	    argument of <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>. If not
	    <code>NIL</code>, it should be a string denoting a proxy
	    server through which the request should be sent.  Or it
	    can be a list of two values - a string denoting the proxy
	    server and an integer denoting the port to use (which
	    will default to 80 otherwise).
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*no-proxy-domains*"></a>
      [Special variable]
      <br><b>*no-proxy-domains*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            A list of domains for which a proxy should not be used.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*drakma-default-external-format*"></a>
      [Special variable]
      <br><b>*drakma-default-external-format*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            The default value for the external format keyword
            arguments of <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>.  The value
            of this variable will be interpreted by <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a>.
            The initial value is the keyword <code>:LATIN-1</code>.
            (Note that Drakma binds <a href="http://weitz.de/flexi-streams/#*default-eol-style*"><code>*DEFAULT-EOL-STYLE*</code></a>
            to <code>:LF</code>).
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*header-stream*"></a>
      [Special variable]
      <br><b>*header-stream*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            If this variable is not <code>NIL</code>, it should be
            bound to a stream to which incoming and outgoing headers
            will be written for debugging purposes.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*text-content-types*"></a>
      [Special variable]
      <br><b>*text-content-types*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            A list of conses which are used by the default value of
            <code xmlns=""><a href="#*body-format-function*">*BODY-FORMAT-FUNCTION*</a></code> to decide
            whether a 'Content-Type' header denotes text content.  The
            car and cdr of each cons should each be a string or
            <code>NIL</code>.  A content type matches one of these
            entries (and thus denotes text) if the type part is <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stgeq_.htm"><code>STRING-EQUAL</code></a>
            to the car or if the car is <code>NIL</code> and if the
            subtype part is <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stgeq_.htm"><code>STRING-EQUAL</code></a>
            to the cdr or if the cdr is <code>NIL</code>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            The initial value of this variable is the list
            <pre>(("text" . nil))</pre> which means that every content
            type that starts with "text/" is regarded as text, no
            matter what the subtype is.
          </p>
        </clix:description></blockquote></p>

    

    <h4 xmlns=""><a name="headers">Headers</a></h4>
      <p>
        This section assembles a couple of convenience functions which
        can be used to access information returned as the third value
        (<code><i>headers</i></code>) of
        <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>.
      </p>
      <p>
        Note that if the server sends <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2">multiple
        headers with the same name</a>, these are comprised into one
        entry by <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>.  The values are
        separated by commas.
      </p>

      <p xmlns=""><a class="none" name="get-content-type"></a>
          [Function]
          <br><b>get-content-type</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">headers</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">list</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Reads and parses a `Content-Type' header and returns it as
            three values - the type, the subtype, and an alist
            (possibly empty) of name/value pairs for the optional
            parameters.  <code xmlns=""><i>headers</i></code> is supposed to
            be an alist of headers as returned by
            <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code>.  Returns
            <code>NIL</code> if there is no such header amongst
            <code xmlns=""><i>headers</i></code>.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="header-value"></a>
          [Function]
          <br><b>header-value</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">name headers</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or string null)</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            If <code xmlns=""><i>headers</i></code> is an alist of headers as
            returned by <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> and
            <code xmlns=""><i>name</i></code> is a keyword naming a header,
            this function returns the corresponding value of this
            header (or <code>NIL</code> if it's not in
            <code xmlns=""><i>headers</i></code>).
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="read-tokens-and-parameters"></a>
          [Function]
          <br><b>read-tokens-and-parameters</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">string &amp;key value-required-p</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">list</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Reads a comma-separated list of tokens from the string
            <code xmlns=""><i>string</i></code>.  Each token can be followed
            by an optional, semicolon-separated list of
            attribute/value pairs where the attributes are tokens
            followed by a #\= character and a token or a quoted
            string.  Returned is a list where each element is either a
            string (for a simple token) or a cons of a string (the
            token) and an alist (the attribute/value pairs).  If
            <code xmlns=""><i>value-required-p</i></code> is <code>NIL</code>,
            the value part (including the #\= character) of each
            attribute/value pair is optional.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="split-tokens"></a>
          [Function]
          <br><b>split-tokens</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">string</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">list</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Splits the string <code xmlns=""><i>string</i></code> into a list
            of substrings separated by commas and optional whitespace.
            Empty substrings are ignored.
          </p>
        </clix:description></blockquote></p>

    

    <h4 xmlns=""><a name="cookies">Cookies</a></h4>
      <p>
        <code xmlns=""><a href="#http-request">HTTP-REQUEST</a></code> can deal with <a href="http://en.wikipedia.org/wiki/HTTP_cookie">HTTP
        cookies</a> if it gets a <a href="#cookie-jar">cookie jar</a>,
        a collection of <code xmlns=""><a href="#cookie">COOKIE</a></code> objects, as its <a href="#arg-cookie-jar">cookie-jar</a> argument.  Cookies sent
        by the web server will be added to the cookie jar (or updated)
        if appropriate and cookies already in the cookie jar will be
        sent to the server together with the request.
      </p>
      <p>
        Drakma will never remove cookies from a cookie jar
        automatically.  You have to do it manually using
        <code xmlns=""><a href="#delete-old-cookies">DELETE-OLD-COOKIES</a></code>.
      </p>

      <p xmlns=""><a class="none" name="cookie"></a>
      [Standard class]
      <br><b>cookie</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Instances of this class represent <a href="http://en.wikipedia.org/wiki/HTTP_cookie">HTTP
            cookies</a>.  If you need to create your own cookies, you
            should use <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_mk_ins.htm"><code>MAKE-INSTANCE</code></a>
            with the initargs <code>:NAME</code>, <code>:DOMAIN</code>,
            <code>:VALUE</code>, <code>:PATH</code>,
            <code>:EXPIRES</code>, <code>:SECUREP</code>, and
            <code>:HTTP-ONLY-P</code> all of which are optional except
            for the first two.  The meaning of these initargs and <a href="#cookie-name">the corresponding accessors</a> should
            be pretty clear if one looks at the <a href="http://curl.haxx.se/rfc/cookie_spec.html">original
            cookie specification</a> (and at <a href="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">this
            page</a> for the <code>HttpOnly</code> extension).
          </p>
          <pre xmlns="http://www.w3.org/1999/xhtml"><span class="repl-output">? </span><span class="repl-input">(make-instance 'drakma:cookie
                 :name "Foo" 
                 :value "Bar"
                 :expires (+ (get-universal-time) 3600)
                 :domain ".weitz.de")</span>
<span class="repl-output">#&lt;COOKIE Foo=Bar; expires=Sun, 09-12-2012 20:37:42 GMT; path=/; domain=.weitz.de&gt;</span>
</pre>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="parse-cookie-date"></a>
          [Function]
          <br><b>parse-cookie-date</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">string</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">universal-time</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Parses a cookie expiry date and returns it as a Lisp <a href="http://www.lispworks.com/documentation/HyperSpec/Body/25_adb.htm">universal
            time</a>.  Currently understands the following formats:
          </p>
          <pre xmlns="http://www.w3.org/1999/xhtml">"Wed, 06-Feb-2008 21:01:38 GMT"
"Wed, 06-Feb-08 21:01:38 GMT"
"Tue Feb 13 08:00:00 2007 GMT"
"Wednesday, 07-February-2027 08:55:23 GMT"
"Wed, 07-02-2017 10:34:45 GMT"</pre>
          <p xmlns="http://www.w3.org/1999/xhtml">
            Instead of "GMT" time zone abbreviations like "CEST" and UTC
            offsets like "GMT-01:30" are also allowed.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            While this function has "cookie" in its name, it might
            come in handy in other situations as well and it is thus
            exported as a convenience function.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="cookie="></a>
          [Function]
          <br><b>cookie=</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie1 cookie2</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">boolean</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          Returns a true value if the cookies
          <code><i>cookie1</i></code> and
          <code><i>cookie2</i></code> are equal.  Two cookies are
          considered to be equal if name and path are equal.
        </clix:description></blockquote></p>

      <p xmlns="">
      [Generic accessors]<br><a class="none" name="cookie-name"></a><b>cookie-name</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">string</clix:returns></i><br><tt>(setf (</tt><b>cookie-name</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-value"></a><b>cookie-value</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or string null)</clix:returns></i><br><tt>(setf (</tt><b>cookie-value</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-domain"></a><b>cookie-domain</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">string</clix:returns></i><br><tt>(setf (</tt><b>cookie-domain</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-path"></a><b>cookie-path</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or string null)</clix:returns></i><br><tt>(setf (</tt><b>cookie-path</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-expires"></a><b>cookie-expires</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or integer null)</clix:returns></i><br><tt>(setf (</tt><b>cookie-expires</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-http-only-p"></a><b>cookie-http-only-p</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">boolean</clix:returns></i><br><tt>(setf (</tt><b>cookie-http-only-p</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><a class="none" name="cookie-securep"></a><b>cookie-securep</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">boolean</clix:returns></i><br><tt>(setf (</tt><b>cookie-securep</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><blockquote></blockquote></p>

      <p xmlns=""><a class="none" name="cookie-jar"></a>
      [Standard class]
      <br><b>cookie-jar</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            An object of this class encapsulates a collection (a list,
            actually) of <code>COOKIE</code> objects. You create a new
            cookie jar with <code>(MAKE-INSTANCE 'COOKIE-JAR)</code>
            where you can optionally provide a list of
            <code xmlns=""><a href="#cookie">COOKIE</a></code> objects with the
            <code>:COOKIES</code> initarg. The cookies in a cookie jar
            are accessed with <code xmlns=""><a href="#cookie-jar-cookies">COOKIE-JAR-COOKIES</a></code>.
          </p>
        </clix:description></blockquote></p>

      <p xmlns="">
      [Generic accessors]<br><a class="none" name="cookie-jar-cookies"></a><b>cookie-jar-cookies</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie-jar</clix:lambda-list></i>
      =&gt;
      <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">list</clix:returns></i><br><tt>(setf (</tt><b>cookie-jar-cookies</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie-jar</clix:lambda-list></i><tt>) <i>new-value</i>)</tt><br><blockquote></blockquote></p>

      <p xmlns=""><a class="none" name="delete-old-cookies"></a>
          [Function]
          <br><b>delete-old-cookies</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie-jar</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">cookie-jar</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Removes all cookies from <code xmlns=""><i>cookie-jar</i></code>
            which have either expired or which don't have an expiry
            date.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*allow-dotless-cookie-domains-p*"></a>
      [Special variable]
      <br><b>*allow-dotless-cookie-domains-p*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            When this variable is not <code>NIL</code>, cookie domains
            containing no dots are considered valid.  The default is
            <code>NIL</code>, meaning to disallow such domains except
            for "localhost".
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*ignore-unparseable-cookie-dates-p*"></a>
      [Special variable]
      <br><b>*ignore-unparseable-cookie-dates-p*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Whether Drakma is allowed to treat `Expires' dates in
            cookie headers as non-existent if it can't parse them.  If
            the value of this variable is <code>NIL</code> (which is
            the default), an error will be signalled instead.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="*remove-duplicate-cookies-p*"></a>
      [Special variable]
      <br><b>*remove-duplicate-cookies-p*</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Determines how duplicate cookies in the response are
            handled, defaults to <code>T</code>.  Cookies are
            considered duplicate using <a href="#cookie="><code>COOKIE=</code></a>.
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            Valid values are:
            <ul>
              <li><code>NIL</code> - duplicates will not be
              removed,</li>
              <li><code>T</code> or <code>:KEEP-LAST</code> - for
              duplicates, only the last cookie value will be kept,
              based on the order of the response header,</li>
              <li><code>:KEEP-FIRST</code> - for duplicates, only the
              first cookie value will be kept, based on the order of
              the response header.</li>
            </ul>
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            Misbehaving servers may send duplicate cookies back in the
            same <code>Set-Cookie</code> header:
          </p>
<pre xmlns="http://www.w3.org/1999/xhtml">HTTP/1.1 200  OK
Server: My-hand-rolled-server
Date: Wed, 07 Apr 2010 15:12:30 GMT
Connection: Close
Content-Type: text/html
Content-Length: 82
Set-Cookie: a=1; Path=/; Secure, a=2; Path=/; Secure
</pre>
          <p xmlns="http://www.w3.org/1999/xhtml">
            In this case Drakma has to choose whether cookie "a" has
            the value "1" or "2".  By default, Drakma will choose the
            last value specified, in this case "2".
          </p>
          <p xmlns="http://www.w3.org/1999/xhtml">
            By default, Drakma conforms to <a href="http://www.w3.org/Protocols/rfc2109/rfc2109">RFC2109
            HTTP State Management Mechanism</a>, section 4.3.3 Cookie
            Management:

            <blockquote>
              <em>
                If a user agent receives a Set-Cookie response header
                whose NAME is the same as a pre-existing cookie, and
                whose Domain and Path attribute values exactly
                (string) match those of a pre-existing cookie, the new
                cookie supersedes the old.
              </em>
            </blockquote>
          </p>
        </clix:description></blockquote></p>
    

    <h4 xmlns=""><a name="conditions">Conditions</a></h4>
      <p>
        This section lists all the condition types that are defined by
        Drakma.
      </p>

      <p xmlns=""><a class="none" name="cookie-date-parse-error"></a>
      [Condition type]
      <br><b>cookie-date-parse-error</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Signalled if Drakma tries to parse the date of an incoming
            cookie header and can't interpret it.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="cookie-error"></a>
      [Condition type]
      <br><b>cookie-error</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Signalled if someone tries to create a COOKIE object
            that's not valid.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="cookie-error-cookie"></a>
          [Generic function]
          <br><b>cookie-error-cookie</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">cookie-error</clix:lambda-list></i>
            =&gt;
            <i><clix:returns xmlns:clix="http://bknr.net/clixdoc">(or cookie null)</clix:returns></i><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            The <code>COOKIE</code> object that caused this error.
            Can be <code>NIL</code> in case such an object couldn't be
            initialized.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="parameter-error"></a>
      [Condition type]
      <br><b>parameter-error</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Signalled if a function was called with inconsistent or
            illegal parameters.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="syntax-error"></a>
      [Condition type]
      <br><b>syntax-error</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Signalled if Drakma encounters wrong or unknown syntax
            when reading the reply from the server.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="drakma-condition"></a>
      [Condition type]
      <br><b>drakma-condition</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Superclass for all conditions related to Drakma.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="drakma-error"></a>
      [Condition type]
      <br><b>drakma-error</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Superclass for all errors related to Drakma.
          </p>
        </clix:description></blockquote></p>

      <p xmlns=""><a class="none" name="drakma-warning"></a>
      [Condition type]
      <br><b>drakma-warning</b><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc">
          <p xmlns="http://www.w3.org/1999/xhtml">
            Superclass for all warnings related to Drakma.
          </p>
        </clix:description></blockquote></p>
    
  

  <h3 xmlns=""><a class="none" name="index">Symbol index</a></h3>
    <ul xmlns="">
<li>
<code><a href="#*allow-dotless-cookie-domains-p*">*allow-dotless-cookie-domains-p*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*body-format-function*">*body-format-function*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*default-http-proxy*">*default-http-proxy*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*drakma-default-external-format*">*drakma-default-external-format*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*header-stream*">*header-stream*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*ignore-unparseable-cookie-dates-p*">*ignore-unparseable-cookie-dates-p*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*no-proxy-domains*">*no-proxy-domains*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*remove-duplicate-cookies-p*">*remove-duplicate-cookies-p*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#*text-content-types*">*text-content-types*</a></code><span class="entry-type">Special variable</span>
</li>
<li>
<code><a href="#cookie">cookie</a></code><span class="entry-type">Standard class</span>
</li>
<li>
<code><a href="#cookie-date-parse-error">cookie-date-parse-error</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#cookie-domain">cookie-domain</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-error">cookie-error</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#cookie-error-cookie">cookie-error-cookie</a></code><span class="entry-type">Generic function</span>
</li>
<li>
<code><a href="#cookie-expires">cookie-expires</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-http-only-p">cookie-http-only-p</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-jar">cookie-jar</a></code><span class="entry-type">Standard class</span>
</li>
<li>
<code><a href="#cookie-jar-cookies">cookie-jar-cookies</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-name">cookie-name</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-path">cookie-path</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-securep">cookie-securep</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie-value">cookie-value</a></code><span class="entry-type">Generic accessor</span>
</li>
<li>
<code><a href="#cookie=">cookie=</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#decode-stream">decode-stream</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#delete-old-cookies">delete-old-cookies</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#drakma-condition">drakma-condition</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#drakma-error">drakma-error</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#drakma-warning">drakma-warning</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#get-content-type">get-content-type</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#header-value">header-value</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#http-request">http-request</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#parameter-error">parameter-error</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#parameter-present-p">parameter-present-p</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#parameter-value">parameter-value</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#parse-cookie-date">parse-cookie-date</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#read-tokens-and-parameters">read-tokens-and-parameters</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#split-tokens">split-tokens</a></code><span class="entry-type">Function</span>
</li>
<li>
<code><a href="#syntax-error">syntax-error</a></code><span class="entry-type">Condition type</span>
</li>
<li>
<code><a href="#url-encode">url-encode</a></code><span class="entry-type">Function</span>
</li>
</ul>
  

</body></html>
